docs(zarr-metadata): say that to_json returns arrays as tuples - #441

🤖 AI text below 🤖

The to_json docstrings and the guide now say what to_json returns: a copy in which each JSON array is a tuple, as the package's JSON types spell an array, so it does not compare equal to what json.loads returns. They point to comparing models instead. The guide had said to_json returns plain containers.

Why

A downstream user (refkv) reported that ZarrV3ArrayMetadata.from_json(doc).to_json() == doc is false and that isinstance(x, list) checks on the result fail. Tuples are deliberate: every JSON TypedDict in the package declares arrays as tuple[...] (covariant, unlike list), and to_json returns what its type declares, as pydantic's model_dump() keeps tuple fields as tuples. What was wrong is the docs: docs/index.md said to_json returns plain containers, while a later section said it returns tuples, and the docstrings only said "refined".

Changes

• The six model to_json docstrings (v3 array, group, consolidated metadata; v2 array, group, .zmetadata) say each array is a tuple and each object a new dict, and point to from_json(document) == model for comparison.
• docs/index.md replaces "to_json returns plain containers" with the same explanation, noting that model comparison also treats an omitted default as equal to the default written out.

just check passed locally.

🤖 Generated with Claude Code